Inside Macintosh: QuickDraw GX Objects /

Chapter 2 - Shape Objects / About Shape Objects

Hit-Testing Shapes

Hit-testing is the process of converting a point in the displayed representation of a shape to a location in the shape object's geometry. You can use hit-testing for shape selection, highlighting, or positioning the caret in text.

When you hit-test a shape, you can in most cases determine which part of a shape's geometry corresponds (within a certain tolerance, or distance) to the point you are testing against. For example, you can tell if a point is exactly on a line, or only close to it; and you can tell which edge of which glyph in a line of text is closest to the hit point.

QuickDraw GX provides a general hit-testing capability for all shapes, a specialized hit-test for testing picture shapes, another specialized hit-test for use with layout shapes, and another specialized hit-test for comparing shapes to specific pixels on a display device. See "Hit-Testing Shapes" beginning on page 2-36 for more information on the specific functions.

When you use the general hit-testing function, it returns one or more shape parts, which specify the parts of the shape's geometry corresponding to the hit point. The parts of a shape's geometry for which you can hit-test depend on the kind of shape. For example, for a typographic shape, the possible parts include those shown on the left side of
Figure 2-5:

• bounds: the bounding rectangle enclosing the entire typographic shape
• glyph bounds: the bounding box for an individual glyph
• glyph first part: the left half of the glyph
• glyph second part: the right half of the glyph
• side bearing: the space on either side of the glyph

As another example, the possible parts for a line include those shown on the right side of Figure 2-5:

• bounds: the bounding rectangle enclosing the start and end points of the line
• edge: the start and end points and all the points between them on the line
• pen: a polygon with half the width of the pen on each side of the line
• geometry: the line's edge plus all area enclosed by it (in this case none, because a line encloses no area)

Figure 2-5 Shape parts for hit-testing

The shape parts that you can test for are defined in the gxShapeParts enumeration, shown on page 2-37 and described in more detail in the chapter "Transform Objects" in this book. Before performing the hit-test, you set up--in the transform object of the shape you are testing--a mask structure that defines all the shape parts that you want to test for. QuickDraw GX tests only for those parts that you specify in the shape parts mask.

For example, if the hit point on the right side of Figure 2-5 is within the tolerance of the geometry part, the function will determine that it corresponds to the bounds, the geometry, the pen, and the edge. If you want to test for geometry alone, then, you could exclude all but geometry from the test. For hit-testing the text on the left side of
Figure 2-5, you might be interested only in whether the hit is within the bounding rectangle of the shape and which side of which glyph it corresponds to, so you can specify the shape parts appropriately.

When you set up the hit-test parameters, you also specify a tolerance. Tolerance is a distance (in units of geometry space), and it defines a circular area centered on the hit point. Any part that falls within that area is considered to correspond to the hit point.